Description
This section will guide through the GetRequest and SetRequest
SNMP PDUs and how they map to JMX attributes and the JBoss SNMP Adaptor.
Each of them will go through the tabular objects only (java.util.List, java.util.Map and arrays the following primitive types int, long, boolean or same supported Object as for the scalar objects).
Both types of tabular object support by JBoss SNMP Adaptor will be used :
-
index based for arrays and java.util.List type of JMX Attributes
-
key based for java.util.Map type of JMX attributes or to access mbean whose name is a wildcard which will return multiple MBeans to query as a table whose ObjectName will be the key.
For both types, the tabular object is comprised of 2 columns :
-
for arrays and java.util.List type of JMX Attributes, the first column will be the indexes and the second column will be the values
-
for java.util.Map type of JMX attributes, the first column will be the keys and the second column will be the values (the SNMP Adaptor will make a copy of the keySet sorted alphabetically so that it can be displayed correctly)
net-snmp will act as a manager and JBoss Application Server SNMP Resource Adaptor as the Agent. The JBoss Application Server SNMP Adaptor is not exposing out of the box MBean attributes exposed as arrays, List or Map so we will use the sample application from
Exposing your Application metrics through SNMP
. The following MBean will be used as an example :
<?xml version="1.0"?>
<attribute-mappings>
<mbean name="test.com:service=SnmpTest" oid-prefix=".1.3.6.1.4.1.2312.100.10.11">
<attribute name="Message" oid=".1" mode="rw"/>
<attribute name="Count" oid=".2"/>
<attribute name="MessageHistory" oid=".3.1" table="true" mode="rw"/>
<attribute name="MessageHistoryAsArray" oid=".4.1" table="true" mode="rw"/>
<attribute name="CountHistory" oid=".5.1" table="true" mode="rw"/>
<attribute name="MessageCountHistory" oid=".6.1" table="true" mode="rw"/>
</mbean>
</attribute-mappings>
Notice that all attributes that will be exposed as table have the table attribute set to"true".
Also as compared to scalar objects, the OID for a tabular object is a bit different. Indeed in SNMP both the Tabular Object itself and its Row Entry (describing the columns of the tabular object) have a distinct OID. So as an example MessageHistory attribute, will have an OID for the table itself, .1.3.6.1.4.1.2312.100.10.11.3 and for its row entry describing the columns .1.3.6.1.4.1.2312.100.10.11.3.1, both being non writable whereas the table contents itself will be writable since mode is set to "rw".
Make sure to deploy the snmp-servlet.war contained in the target directory of the snmp-servlet.zip from Exposing your Application metrics through SNMP in the deploy directory of the JBoss Application Server profile that is currently running
Then let's assume we set a message then refresh the pages 3 times, then set another message and refresh again 3 times.
Index Based Tabular Objects
MessageHistory Attribute is of type java.util.List<String> so is a Tabular Object index based that will be used for the following sub sections as an example.
Exposing a JMX Attribute as Tabular Object (Index Based) and reading its value through SNMP GetRequest
To read the first message that was set in MessageHistory, the query OID should be the concatenation of the oid prefix (.1.3.6.1.4.1.2312.100.10.11) + the MessageHistory OID (.3.1) + the value column (.2) + the index to retrieve the value from (.1) (remember that to access the index 0, .1 should be used because .0 are reserved for scalar objects) so the following command should be issued :
snmpget -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1.2.1
which will give the following output
iso.3.6.1.4.1.2312.100.10.11.3.1.2.1 = STRING: "first message"
Then to get the second message, the following command should be issued
snmpget -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1.2.2
which will give the following output
iso.3.6.1.4.1.2312.100.10.11.3.1.2.2 = STRING: "second message"
and so on in keeping increasing the last value until the index doesn't match anything.
snmpget -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1.2.3
will give
iso.3.6.1.4.1.2312.100.10.11.3.1.2.3 = No Such Object available on this agent at this OID
The other and standard way to find out the size of the table is to use GetNextRequest SNMP PDU, which is covered in another section of this page
Exposing a JMX Attribute as Tabular Object (Index Based) and setting its value through SNMP SetRequest
To set a value in a tabular object that is index based the same principle is applied the query OID should be the concatenation of the oid prefix (.1.3.6.1.4.1.2312.100.10.11) + the MessageHistory OID (.3.1) + the value column (.2) + the index to retrieve the value from (.1) (remember that to access the index 0, .1 should be used because .0 are reserved for scalar objects) so the following command should be issued to modify the second message of the MessageHistory table
snmpset -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1.2.2 s "overriding second message"
which will give the following output
iso.3.6.1.4.1.2312.100.10.11.3.1.2.2 = STRING: "overriding second message"
Note: It is not currently possible to create or remove rows in a table through the JBoss SNMP Adaptor
Iterating through a Tabular Object (Index Based) through SNMP GetNextRequest
Rows of a table can be read by specifying column OIDs in the variable bindings of the request, so by specifying the table OID ie for MessageHistory table attribute the OID will be .1.3.6.1.4.1.2312.100.10.11.3.1, it is actually possible to iterate through the full table by issuing a set of GetNextRequest SNMP PDU. To iterate through the MessageHistory table the following commands should be issued :
snmpgetnext -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1
iso.3.6.1.4.1.2312.100.10.11.3.1.2.1 = STRING: "first message"
By querying the table OID, this gives us the first entry OID and value in the table, that can be used to get the next entry OID and value so the following command should be issued
snmpgetnext -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1.2.1
iso.3.6.1.4.1.2312.100.10.11.3.1.2.2 = STRING: "overriding second message"
this gives us the second entry OID and value in the table, that can be used to get the next entry OID and value so the following command should be issued
snmpgetnext -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1.2.2
iso.3.6.1.4.1.2312.100.10.11.4.1.2.1 = STRING: "first message"
notice how the OID jumped from attribute 3.1 (full OID queried was iso.3.6.1.4.1.2312.100.10.11.3.1.2.2) to 4.1 (full OID iso.3.6.1.4.1.2312.100.10.11.4.1.2.1) because there was no more rows in the table the GetNextRequest returned the next OID which happens to be the next attribute (MessageHistoryAsArray) which is also a tabular object (same content as MessageHistory but returned as String array)
Iterating through a Tabular Object (Index Based) through SNMP GetBulkRequest
The GetBulkRequest was introduced in SNMP version 2 because iterating through a table with GetNext proved to be tedious and inefficient. So GetBulkRequest was introduced to allow fetching a table completely with one request instead of multiple GetNext requests. So to iterate through the MessageHistory table the following command should be issued :
snmpbulkget -v 3 -Cr2 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.3.1
which give the following output
iso.3.6.1.4.1.2312.100.10.11.3.1.2.1 = STRING: "first message"
iso.3.6.1.4.1.2312.100.10.11.3.1.2.2 = STRING: "overriding second message"
Key Based Tabular Objects
MessageCountHistory Attribute is of type java.util.Map<String, Integer> so is a Tabular Object key based that will be used for the following sub sections as an example.
Iterating through a Tabular Object (Key Based) through SNMP GetNextRequest
As opposed to an index based Tabular Object, there is no index to iterate through for the rows of a table, so there is no way to issue a GetRequest PDU directly except if the table contents is already known to the querier. So as for index based tabular objects by specifying the table OID ie for MessageCountHistory table attribute the OID will be .1.3.6.1.4.1.2312.100.10.11.6.1, it is actually possible to iterate through the full table by issuing a set of GetNextRequest SNMP PDU. To iterate through the MessageCountHistory table the following commands should be issued :
snmpgetnext -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.6.1
which gives the following output :
iso.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101 = INTEGER: 3
The interesting thing to notice here is the OID given back in response. The OID is a concatenation of the table entry OID (.1.3.6.1.4.1.2312.100.10.11.6.1) and of the ASN.1 representation of the first entry key of the java.util.Map MessageCountHistory attribute (ie "first message"), to get the next key of the map, the OID of the response has to be used just like for regular index based tabular objects so to get the next entry OID and value the following command should be issue
snmpgetnext -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101
which gives the following output :
iso.3.6.1.4.1.2312.100.10.11.6.1.2.115.101.99.111.110.100.32.109.101.115.115.97.103.101 = INTEGER: 6
Again the OID is a concatenation of the table entry OID (.1.3.6.1.4.1.2312.100.10.11.6.1) and of the ASN.1 representation of the second entry key of the java.util.Map MessageCountHistory attribute (ie "second message"). And so on to iterate through the whole table.
Iterating through a Tabular Object (Key Based) through SNMP GetBulkRequest
The GetBulkRequest was introduced in SNMP version 2 because iterating through a table with GetNext proved to be tedious and inefficient. So GetBulkRequest was introduced to allow fetching a table completely with one request instead of multiple GetNext requests. So to iterate through the MessageHistory table the following command should be issued :
snmpbulkget -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.6.1
which give the following output
iso.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101 = INTEGER: 3
iso.3.6.1.4.1.2312.100.10.11.6.1.2.115.101.99.111.110.100.32.109.101.115.115.97.103.101 = INTEGER: 6
Exposing a JMX Attribute as Tabular Object (Key Based) and reading its value through SNMP GetRequest
Now that the OID of the rows of the key based table are known, they can be read by querying the OID that should be the concatenation of the oid prefix (.1.3.6.1.4.1.2312.100.10.11) + the MessageCountHistory OID (6.1) + the value column (.2) + the ASN.1 representation of the key of the table whose value wants to be retrieved so for retrieving the "first message" corresponding value in the Map the following command should be issued :
snmpget -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101
which will give the following output
iso.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101 = INTEGER: 3
Exposing a JMX Attribute as Tabular Object (Key Based) and setting its value through SNMP SetRequest
Now that the OID of the rows of the key based table are known, they can be set by querying the OID that should be the concatenation of the oid prefix (.1.3.6.1.4.1.2312.100.10.11) + the MessageCountHistory OID (6.1) + the value column (.2) + the ASN.1 representation of the key of the table whose value wants to be set so for changing the "first message" corresponding value in the Map the following command should be issued :
snmpset -v 3 -u TEST -a MD5 -A "maplesyrup" -x DES -X "maplesyrup" -l authPriv 127.0.0.1:1161 .1.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101 i 69
which will give the following output
iso.3.6.1.4.1.2312.100.10.11.6.1.2.102.105.114.115.116.32.109.101.115.115.97.103.101 = INTEGER: 69
Note: It is not currently possible to create or remove rows in a table through the JBoss SNMP Adaptor